<html>
<head>
<title>Elda -- an implementation of the Linked Data API</title>
<link href="style.css" type="text/css" rel="stylesheet"></link>
</head>
<body>

<div class="main">

<div class="heading">
<a href="http://www.epimorphics.com">
<img class="logo" src="epilogo-240.png">
</a>
<h1>Elda 1.2.25</h1>
<h2>An implementation of the Linked Data API</h2>
</div>

<h1 a name="elda-common">Elda Common</h1>

<p>
Elda Common provides a way of dropping Elda
into an existing webapp container with a minimum of fuss.
(While we write "Tomcat" below as the webapp container,
any suitably configurable one &mdash; <i>eg</i> Jetty
&mdash; will do. We assume that you have the necessary
access permissions to install or update Tomcat and
run it on your preferred port.)
</p>

<p>
There are three components to Elda Common:

<ul>
	<li>
		The Elda Common War, a Maven artifact you can download
		in the usual way as file 
		<code>elda-common-VERSION.war</code>.
	</li>

	<li>
		The Elda Assets War, a Maven artifact you can download
		in the usual way as <code>elda-assets-VERSION.war</code>.
	</li>

	<li>
		<a href="http://elda.googlecode.com/hg/elda-assets/src/main/webapp/specs/ROOT_minimal.ttl">
		Minimal LDA configurations</a> demonstrating Elda Common setup.
	</li>
</ul>

The Common and Assets files must have the same version.
</p>

<p>
To use Elda Common, you add both .war files to your Tomcat
configuration. Doing so may be as simple as dropping them
into the appropriate <code>webapps</code> directory. 
You need both .war files;
Elda Common contains the LDA-handling Java code and Elda
Assets provides styleheets, scripts, css, <i>etc</i> which Elda
Common refers to or loads. There is also an 
<code>elda-bundled</code>code>
artifact whose <code>elda-bundled.war</code> combines 
<code>elda-common</code> and <code>elda-assets</code> into one item.
</p>

<p>
By default, Elda Common assumes that Elda Common's context
path is <code>elda-common</code> and Elda Assets's context
path is <code>elda-assets</code>. If you want them to use
different context paths, you will need to also change the
name and contents of the LDA config (see below). You can
install multiple copies of Elda Common with different
context paths, all sharing the same assets. (You can also
have multiple different assets if necessary.) You can 
install Elda as ROOT.war so that Tomcat is serving the
URI templates with no prefix, so long as the name of the
assets .war does not collide with any of those templates.
</p>

<p>
Elda Common loads its LDA configurations from
<code>/etc/elda/conf.d/{APP}/*.ttl</code>, where
<code>{APP}</code> is the context path of that instance
of Elda Common. This means that each instance may have
multiple configs that it can load, and different instances
can load different files. (See the <code>web.xml</code>
for the setting of this configuration path.)
</p>

<p>
The LDA configurations contain references to the assets
webapp, as seen in the minimal configuration file
supplied. For a given <code>API:api</code> in a configuration file,
the location of the assets is given in a variable
binding:
</p>

<pre>
; api:variable [api:name "_resourceRoot"; api:value "http://<i>hostAndPort</i>/<i>assetPath</i>/"]
</pre>

<p>
The <i>hostAndPort</i> will usually be <b>localhost:8080</b>
or <b>localhost:80</b>, and <i>assetPath</i> will by default
be <b>elda-assets</b> unless the asset .war is renamed to some
other context or you are using <code>elda-bundled</code>.
</p>

<p>
Similarly, if the configuration is generating HTML using the
Elda XSLT renderer, the stylesheets are loaded from the
assets according to the binding on the XsltFormatter by:
</p>

<pre>
; api:stylesheet "http://<i>hostAndPort</i>/<i>stylesheetPath</i>/xslt/result.xsl"
</pre>

<p>
Again, if the stylesheet has moved, this binding must be
changed accordingly.
</p>

<p>
Elda provides several example minimal configurations, different
only in their intended environments:

<table style="margin:1ex">
<tr>
	<td><a href="specs-1.2.25/minimal-named-bundled-8080-config.ttl">minimal-named-bundled-8080-config.ttl</a></td>
	<td>bundled non-ROOT configuration running on port 8080.</td>
</tr>

<tr>
	<td><a href="specs-1.2.25/minimal-named-or-ROOT-split-8080-config.ttl">minimal-named-or-ROOT-split-8080-config.ttl</a></td>
	<td>split assets and common on port 8080, for both ROOT and non-ROOT use.</td>
</tr>

<tr>
	<td><a href="specs-1.2.25/minimal-named-split-80-config.ttl">minimal-named-split-80-config.ttl</a></td>
	<td>split assets and common on port 80 for non-ROOT use.</td>
</tr>

<tr>
	<td><a href="specs-1.2.25/minimal-ROOT-bundled-8080-config.ttl">minimal-ROOT-bundled-8080-config.ttl</a></td>
	<td>ROOT bundled and running on port 8080.</td>
</tr>

</table>

</p>

<p>
The configuration itself is a place-holder with
three uri templates:

<table style="margin:1ex">
	<tr>
		<td><code>/anything</code></td>
		<td>to provide some example results</td>
	</tr>
	<tr>
		<td><code>/about?resource={someURI}</code></td>
		<td>provides information (ie properties and their values) about the 
			resource <code>someURI</code></td>
	</tr>
	<tr>
		<td><code>/mentions?resource={someURI}</code></td>
		<td>finds items which have <code>someURI</code> as the value of some property.</td>
	</tr>

</table>
</p>

<p>
The minimal configuration assumes that a SPARQL endpoint is
available on <code>localhost:3030/store</code>. You can 
replace this endpoint with a different one, or for development
purposes you can run a <a href="http://jena.apache.org/documentation/serving_data/">Fuseki</a>
SPARQL server serving RDF data of your choice.
</p>

<h2>Reload on change</h2>

<p>
When Elda handles a request, if it has been "sufficiently
long" since the last request, it will check to see if it
is up-to-date with its configuration and, if not, reload it.
</p>

<p>
"Sufficently long" defaults to 5 seconds and can be adjusted
by creating the file <code>/etc/elda/conf.d/{APP}/delay.int</code>.
<code>APP</code> is the context path for this Elda webapp. The
content of the file must be an integer number of millseconds.
</p>

<p>
"Up-to-date" means that none of the configuration files or their
directories are time-stamped later than the time that the
configurations were loaded.
</p>

<p>
Elda does not check that the <i>contexts</i> of these files
have changed, so it is sufficient to simple <code>touch</code>
one of the appropriate files.
</p>

<h1><a name="beyond"></a>Inside Elda Common</h1>

<p>
(The Elda standalone jar is just a delivery mechanism for getting
started with LDA functionality: it packs together the Elda code
(a merge of Elda Common and Elda Assets) and a Jetty server.)
</p>

<p>
To use Elda for your own webapps, you can use Elda Common
(suitably replacing the minimal LDA config), produce your
own merge of Common and Assets, or tweak the Elda Standalone
warfile. You will need to edit the web.xml appropriately.
</p>

<p>
If you have downloaded the Elda repository, then you can
rebuild the Elda working jar (lda-VERSION.jar) 
and webapp using <a href="http://maven.apache.org/">Maven</a>;
see below.
</p>

<h2><a name="anatomy"></a>Anatomy of the Elda's web.xml</h2>

<p>
Elda runs as a bunch of JAX-RS resources within a Jersey
container. The LDA configurations it loads are specified
by the value of a <i>context parameter</i>.
</p>

<pre>
&lt;context-param>
   &lt;param-name>com.epimorphics.api.initialSpecFile&lt;/param-name>
   &lt;param-value>/etc/elda/conf.d/{APP}/*.ttl&lt;/param-value>
&lt;/context-param>
</pre>

<p>
For non-Common uses of Elda, you can have multiple comma-separated
configuration directives in a single &lt;param-value&gt;. Spaces, tabs,
and newlines within the value are discarded.
</p>

<p>
	Each directive is a filename, with an optional leading
	prefix specification consisting of a name followed by 
	<code>::</code>.
</p>

<p>
	If the prefix is supplied, then all of the URI templates
	in the configuration are implicitly prefixed with it;
	this allows different configurations to be loaded together
	even if they happen to share URI templates.
</p>

<p>
	The provided filename is a webapp-relative unless it starts
	with "/". Any occurence of the string "{APP}" is replaced 
	by the context path, and the character "*" matches any sequence
	of characters, allowing multiple configuration files to be
	specified at one time and appropriately to this webapp.
</p>

<p>
	The string <code>{file}</code> in the prefix is replaced
	by the base of the filename with any trailing <code>.ttl</code>
	removed. The string <code>{api}</code> in the prefix is replaced
	by the local name(s) of the API resouce(s) in the spec.
</p>

<p>
	If the prefix contains a '*' character, it is replaced by whatever
	characters matched any wildcard '*'s in the last segment of the
	filename. (If there is more than one such '*', the matching groups
</p>

<h4>example</h4>

<p>
	Given the directive <code>A*B::/etc/elda/*.ttl</code> and
	files <code>x.ttl</code>, <code>y.ttl</code> and <code>z.text</code>
	in <code>/etc/elda</code>, the configuration file <code>x.ttl</code> 
	will be loaded and given prefix <code>AxB</code> and the
	file <code>y.ttl</code> will be loaded with prefix <code>AyB</code>.
	<code>z.text</code> is ignored as it does not match the filename.
</p>

<h3><a name="servlet"></a>The Elda Jersey filter</h3>

<p>
Elda runs as a Jersey filter applied to all of the paths for
this context path. A path that does not match any LDA 
URI template produces a NOT FOUND status that by default
is handled by Tomcat to serve a static file if one exists
with that pathname. JAX RS resources are located in the
package <code>com.epimorphics.lda.restlets</code>.
</p>

<pre>
 &lt;filter&gt;
    &lt;filter-name&gt;Jersey Web Application&lt;/filter-name&gt;
    &lt;filter-class&gt;com.sun.jersey.spi.container.servlet.ServletContainer&lt;/filter-class&gt;
    
    &lt;init-param&gt;
      &lt;param-name&gt;com.sun.jersey.config.property.packages&lt;/param-name&gt;
	  &lt;param-value&gt;<b>com.epimorphics.lda.restlets</b>&lt;/param-value&gt;
    &lt;/init-param&gt;
        
    &lt;init-param&gt;
	  &lt;param-name&gt;com.sun.jersey.config.feature.<b>FilterForwardOn404</b>&lt;/param-name&gt;
	  &lt;param-value&gt;<b>true</b>&lt;/param-value&gt;
    &lt;/init-param&gt;
        
    &lt;init-param&gt;
         &lt;param-name&gt;com.sun.jersey.spi.container.ContainerRequestFilters&lt;/param-name&gt;
         &lt;param-value&gt;com.sun.jersey.api.container.filter.PostReplaceFilter&lt;/param-value&gt;
     &lt;/init-param&gt;
&lt;/filter&gt;
    
&lt;filter-mapping&gt;
    &lt;filter-name&gt;Jersey Web Application&lt;/filter-name&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;

&lt;servlet-mapping&gt;
    &lt;servlet-name&gt;default&lt;/servlet-name&gt;
    &lt;url-pattern&gt;&lt;b&gt;/*&lt;b&gt;&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;

&lt;listener&gt;
  &lt;listener-class>com.epimorphics.lda.restlets.RouterRestlet$Init&lt;/listener-class&gt;
&lt;/listener&gt;
</pre>

<p>
The (optional) <code>Init</code> listener forces Elda to load its
configurations when the webapp starts. If this listener is
omitted, Elda will load configurations when the first request
arrives.
</p>

<p>
Everything else is handled by the default servlet, which
delivers all the static files inside the webapp.
</p>

<h3><a name="rewriting"></a>URL rewriting</h3>

<p>
Elda Common does not do URL rewriting; it handles all of the
requests sent to its context, either as URI templates or
as static files. For applications that need to present
different URIs to an external interface from those used within
the application, you can either use on of the existing
within-servlet URI rewriting engines or having a front-end
server, <i>eg</i> Apache or Nginx, which selectively rewrites
or discards requests with (un)suitable URIs.
</p>

<h3><a name="loading-config"></a>Obsolete: the Loader servlet</h3>

<p>
	Previous versions of Elda had their configuration specified
	within a load-on-startup Loader servlet with an init-param
	<code>initialSpecFile</code> supplying the configuration file names.
	This approach to configuration is now <i>obsolete</i> as it lead
	to technical difficulties; it is supported in Elda 1.2.25 to
	allow users to migrate to the new configuration process.
</p>

<h1><a name="shortname-restrictions"></a>Restrictions on shortname selection</h1>

<p>
    In an (E)lda configuration file, the configurer may define 
    "short names" for properties and resources. However, the
    current supplied example XSLT stylesheets expect that the
    properties used to define the metadata about a query and
    its results have certain specified shortnames.
</p>

<p>
    Elda reserves and predefines those shortnames; the configuation
    writer should not attempt to define them themselves.
</p>

<p>
    The reserved names are the local names (except where otherwise
    indicated) of the properties:
</p>

<table style="margin-left: 2ex">
	<thead> <tr><th>prefix</th> <th>term</th> <th>term</th> <th>term</th></tr></thead>
	<tr> <td>rdf</td>  <td>type</td> <td>value</td> <td>&nbsp;</td> </tr>
	<tr> <td>rdfs</td>  <td>label</td> <td>comment</td> <td>&nbsp;</td> </tr>

	<tr> <td>xsd</td>  <td>integer</td> <td>decimal</td> <td>string</td> </tr>
	<tr> <td>xsd</td>  <td>boolean</td> <td>int</td> <td>short</td> </tr>
	<tr> <td>xsd</td>  <td>byte</td> <td>long</td> <td>double</td> </tr>
	<tr> <td>xsd</td>  <td>date</td> <td>time</td> <td>&nbsp;</td> </tr>

	<tr> <td>doap</td>  <td>implements</td> <td>releaseOf</td> <td>homepage</td> </tr>
	<tr> <td>doap</td>  <td>repository</td> <td>browse</td> <td>location</td> </tr>
	<tr> <td>doap</td>  <td>wiki</td> <td>revision</td> <td>&nbsp;</td> </tr>
	<tr> <td>doap</td>  
		<td>bug-database <div>(as bug_database)</div></td> 
		<td>programming-language <div>(as programming_language)</div></td> 
		<td>&nbsp;</td> 
	</tr>

	<tr> <td>opmv</td>  <td>software</td> <td>&nbsp;</td> <td>&nbsp;</td> </tr>

	<tr> <td>api</td>  <td>definition</td> <td>extendedMetadataVersion</td> <td>page</td> </tr>
	<tr> <td>api</td>  <td>items</td> <td>item</td> <td>processor</td> </tr>
	<tr> <td>api</td>  <td>property</td> <td>selectionResult</td> <td>termBinding</td> </tr>
	<tr> <td>api</td>  <td>variableBinding</td> <td>viewingResult</td> <td>wasResultOf</td> </tr>
	<tr> <td>dct</td>  <td>format</td> <td>hasFormat</td> <td>hasPart</td> </tr>
	<tr> <td>dct</td>  <td>hasVersion</td> <td>isFormatOf</td> <td>isPartOf</td> </tr>
	<tr> <td>dct</td>  <td>isVersionOf</td> <td>&nbsp;</td> <td>&nbsp;</td> </tr>
	<tr> <td>elda</td>  <td>listURL</td> <td>sparqlQuery</td> <td>&nbsp;</td> </tr>
	<tr> <td>foaf</td>  <td>isPrimaryTopicOf</td> <td>primaryTopic</td> <td>&nbsp;</td> </tr>
	<tr> <td>OpenSearch</td>  <td>itemsPerPage </td> <td>startIndex</td> <td>&nbsp;</td> </tr>
	<tr> <td>sparql</td>  <td>endpoint</td> <td>query</td> <td>url</td> </tr>
	<tr> <td>xhv</td>  <td>first</td> <td>next</td> <td>prev</td> </tr>

</table>

<h1><a name="shortname-mode"></a>Elda shortname creation</h1>

<p>
	When Elda renders a result-set graph using JSON or XML (and
	consequently HTML), URIs used as predicates are given short
	names if they have not been given in the configuration.
	Where possible these names should satisfy the shortname
	grammar; this allows them to be used as XML element names.
	Elda splits the URI into its <i>namespace</i> and 
	<i>local name</i> parts and uses the localname as the
	basis for the generated shortname.
</p>

<p>
	<i>NOTE</i>. Elda uses the Jena XML-derived rule to
	split URIs, defining the local name as being the longest
	possible NCName that is a suffix of the URI. That name
	is not necessarily the same as that after a '#' or
	final '/' of a URI. Because the local name is an NCName
	it is automatically a legal XML element name.
</p>

<p>
	Elda has three <i>shortname modes</i> for generating
	shortnames. The mode for a given format may be
	specified by setting the property <code>elda:shortnameMode</code>
	on a declared <code>formatter</code> of the configuration
	to one of the values <code>elda:roundTrip</code>,
	<code>elda:preferLocalname</code>, or
	<code>elda:preferPrefixes</code>. The default for
	all renderers is <code>preferLocalname</code>.
</p>

<p>
	Elda follows these rules for converting a URI 
	(not already given a shortname) with namespace N 
	and local name L into a shortname:
</p>

<ol>
	<li>
		if the mode is <code>preferLocalname</code>,
		and this is the only URI with this local name,
		and L is not already a shortname,
		its shortname is L.
	</li>
	
	<li>
		if the namespace has an available prefix P
		and P_L is not already a shortname, then
		its shortname is P_L.
	</li>

	<li> 
		if mode is not <code>roundTrip</code>, the
		shortname is L_N, where N is a (weak) hash 
		of the namespace. 
	</li>

	<li>
		otherwise the shortname is a reversible
		encoding of the full URI into a shortname
		(that is not short).
	</li>
</ol>

<p>
	The bindings of short names to full URIs &mdash;
	the <i>term bindings</i> &mdash; are made available
	as metadata in the rendered result. This metadata
	is by default only generated for HTML renderings;
	to have it present in JSON, XML, or RDF renderers,
	specify the query parameter <code>_metadata=bindings</code>
	or <code>_metadata=all</code> on the LDA request.
</p>

<h1><a name="velocity"></a>Velocity template rendering</h1>

<p>
    This release of Elda includes the ability to use 
    <a href="http://velocity.apache.org/">Velocity</a>
    templates for rendering. This feature is <i>provisional</i>;
    it may change significantly in future releases.
</p>

<p>
    To use the Velocity renderer to generate HTML, attach this formatter to
    your API spec:
</p>

<pre>
&lt;yourSpec> api:defaultFormatter
	[a elda:VelocityFormatter
	; api:name "html"
	; elda:className "com.epimorphics.lda.renderers.VelocityRendererFactory"
	; api:mimeType "text/html"
	]
</pre>

<p>
    By default, this will render the template
    <code>page-shell.vm</code> found in <code>{_velocityRoot}</code>
    if <code>_velocityRoot</code> is defined, or in
    <code>{_resourceRoot/vm}</code> otherwise. (<code>_resourceRoot</code>
    has a default value.) 
</p>

<p>
    (Previous versions of Elda loaded templates from 
    <code>webapp/WEB-INF/classes</code>, but with the split between
    elda-common and elda-assets, the templates have been moved out
    of the Elda code webapp.)
</p>

<p> 
    To change the
    rendered template, set the <code>api:stylesheet</code>
    property of the formatter to the name of the desired
    template.
</p>

<p>
    You may choose to specify a Velocity formatter as a property of an
    endpoint rather than as the API-wide default.
</p>

<p>
    You can change the associated suffix of the formatter by changing the
    value of its <code>api:name</code> property, and change the content-type
    of the generated page by changing the value of the api:mimeType property.
</p>

<p>
    Elda looks for <code>{_resourceRoot}/velocity.properties</code>
    and, if it exists and is non-empty, uses it as its Velocity 
    configuration. If there's no such file, or it contains no
    property definitions, Elda uses a default configuration that
    fetches templates from <code>{_velocityRoot}</code> if it
    is defined and from <code>{_resourceRoot}/vm</code> if not.
</p>

<p>
    When rendering a page using Velocity, Elda binds several
    names in the context:
</p>

<table style="margin-left: 2ex">
    <thead><tr><th>name</th><th>value</th></tr></thead>

    <tr>
	<td>thisPage</td>
	<td>
		A WrappedNode for a resource with the URI of this
		page.
	</td>
    </tr>
    
    <tr>
	<td>isItemEndpoint</td>
	<td>
		A boolean, true iff this page is for an item endpoint.
	</td>
    </tr>
    
    <tr>
	<td>isListEndpoint</td>
	<td>
		A boolean, true iff this page is for a list endpoint.
	</td>
    </tr>
    
    <tr>
	<td>primaryTopic</td>
	<td>
		A WrappedNode for the primary topic of this page, only defined
		if this page is for an item endpoint.
	</td>
    </tr>

    <tr>
	<td>names</td>
	<td>
		a map from resources to their short names, passed
		when needed to methods on <code>WrappedNode</code>s.
	</td>
	</tr>

    <tr>
	<td>formats</td>
	<td>
		a list of Format objects in order of their names.
		Each Format has a getName and getLink method;
		a format's Link is the URI needed to fetch the
		version of the current page in this format.
	</td>
    </tr>

    <tr>
	<td>items</td>
	<td>
		the list of selected items. Each item is a 
		<code>WrappedNode</code>.
	</td>
    </tr>

    <tr>
	<td>meta</td>
	<td>
		A map from string pathnames to <code>WrappedNode</code>
		values. Each pathname is the dot-separated concatenation
		of the short names of the properties in the path. The
		proeprty chains are those of the metadata in the result
		model, disregarding the <code>termBinding</code>s and
		the <code>variableValues</code> since these have their own
		context variables.
	</td>
    </tr>

    <tr>
	<td>vars</td>
	<td>
		A map from LDA variable names to <code>WrappedNode</code>s
		representing their values.
	</td>
    </tr>

    <tr>
	<td>ids</td>
	<td>
		An IdMap object which contains a map from Resources to their 
		identifiers for use in HTML <code>id=</code> attributes.
	</td>
    </tr>
</table>

<p>
	WrappedNodes are wrappers round Jena RDFNodes. When they are created,
	they are given a ShortNames object to allow them to render their short
	names and an IdMap object to hold their allocated Id. They have the following methods:
</p>

<table>
	<thead>
		<tr>
			<th>signature</th>
			<th>description</th>
		</tr>
	</thead>
<tr>
	<td>boolean equals(Object other)</td>
	<td>
		A WrappedNode is .equals to another object if
		that object is a WrappedNode and their underlying
		RDFNodes are equal.
	</td>
</tr>
<tr>
	<td>String getId()</td>
	<td>
		Answer the id of this WrappedNode, allocating a
		fresh one if necessary.
	</td>
</tr>

<tr>
	<td>WrappedString getLabel()</td>
	<td>
		Return this wrapped resource's preferred label;
		the first literal of (a) this resources skos:prefLabel,
 		(b) an unlanguaged rdfs:label, (c) a languaged
		rdfs:label, (d) the local name of this resource.
	</td>
</tr>

<tr>
	<td>WrappedString getLabel(String wantlanguage)</td>
	<td>
	    If wantLanguage is "", return getLabel(). Otherwise, 
	    return the lexical form of some label of this wrapped 
    	    resource which has <code>wantLanguage</code>. If there isn't
    	    one, return some lexical form with no language. If there
    	    isn't one, return the local name of the resource.
	</td>
</tr>

<tr>
	<td>boolean isJustALabel()</td>
	<td>
		Returns true if this WrappedNode is a Resource node
		which has exactly one property, and that property
		has predicate <code>rdfs:label</code>.
	</td>

</tr>

<tr>
	<td>WrappedString shortForm()</td>
	<td>
		If this node is a wrapped Resource, return the
		shortname associated with that Resource or its
		localname if it has no shortname. If this node
		is a wrapped Literal, return the lexical form of
		that literal.
	</td>
</tr>

<tr>
	<td>WrappedString getURI</td>
	<td>
		If this WrappedNode is a Resource, return its URI.
	</td>
</tr>

<tr>
	<td>boolean isLiteral</td>
	<td>
		Return true iff this WrappedNode is a wrapped Literal.
	</td>
</tr>

<tr>
	<td>boolean isResource</td>
	<td>
		Return true iff this WrappedNode is a wrapped Resource
		(which may be a blank node).
	</td>
</tr>

<tr>
	<td>boolean isAnon</td>
	<td>
		Return true iff this WrappedNode is a blank node.
	</td>
</tr>

<tr>
	<td>String getLanguage</td>
	<td>
		If this node is a wrapped Literal, return its language
		if any, otherwise return the empty string.
	</td>
</tr>

<tr>
	<td>WrappedString getLiteralType()</td>
	<td>
		Return the short form of the URI representing the type
		of this wrapped literal node.
	</td>
</tr>

<tr>
	<td>Object getLiteralValue()</td>
	<td>
		Return the unadorned value of this literal.
	</td>
</tr>

<tr>
	<td>boolean isList</td>
	<td>
		Return true iff this WrappedNode wraps a Resource representing
		an RDF list.
	</td>
</tr>

<tr>
	<td>List&lt;WrappedNode>asList</td>
	<td>
		Return a Java list of WrappedNodes wrapping the elements of
		the RDF list represented by this WrappedNode.
	</td>
</tr>

<tr>
	<td>List&lt;WrappedNode> getProperties</td>
	<td>
		Return a Java list of WrappedNodes which are the 
		wrapped form of the different properties of this
		WrappedNode.
	</td>
</tr>

<tr>
	<td>List&lt;WrappedNode> getInverseProperties</td>
	<td>
		Return a Java list of WrappedNodes which are
		the wrapped form of predicates P where there is some
		subject S such that (S, P, this wrapped node).
	</td>
</tr>

<tr>
	<td>List&lt;WrappedNode> getValues(WrappedNode property)</td>
	<td>
		Return a Java list of WrappedNodes which are the
		objects of all statements for which this WrappedNode
		is the subject and the argument <code>property</code>
		is the predicate. (This argument will typically be
		an element from the <code>getProperties</code> list.)
	</td>
</tr>

<tr>
	<td>List&lt;WrappedNode> getInverseValues(WrappedNode property)</td>
	<td>
		Return a Java list of WrappedNodes which are the
		subjects of all statements for which this WrappedNode
		is the object and the argument <code>property</code>
		is the predicate. (This argument will typically be
		an element from the <code>getInverseProperties</code> list.)
	</td>
</tr>

<tr>
	<td>WrappedNode change(String prefix, WrappedNode p, WrappedNode v)</td>
	<td>
		Return a new WrappedNode wrapping a resource with the same URI
		as this one, except that all query parameters whose name is
		<code>prefix</code> prefixed onto p's shortname have been 
		discarded and replaced by a parameter with that name and with 
		value v.toString().
	</td>
</tr>

</table>

<p>
	Where a String result might contain HTML-significant characters,
	WrappedNodes return a WrappedString object.
</p>

<table>
	<thead>
		<tr>
			<th>signature</th>
			<th>description</th>
		</tr>
	</thead>

<tr>
	<td>WrappedString cut()</td>
	<td>
		Returns a new wrapped string who's content is the
		content of this wrapped string but with spaces
		inserted in place of runs of '_' and between a
		lower-case letter followed by an upper-case one,
		with that letter converted to lower-case.
	</td>
</tr>

<tr>
	<td>String toString()</td>
	<td>
		Return the content of this WrappedString,
		performing HTML escaping.
	</td>
</tr>

<tr>
	<td>String raw()</td>
	<td>
		Return the content of this WrappedString
		without escaping.
	</td>
</tr>
</table>


<h1><a name="additional-elda-features"></a>Additional Elda features</h1>

<h2><a name="variables"></a>Configuration variables</h2>

<p>
    Elda reserves LDA variable names that begin "_" for
    configuration purposes.
</p>

<h3>Variables used by the stylesheet</h3>

<p>
    The built-in Elda stylesheet generates HTML pages
    that require http access to images, CSS stylesheets,
    and Javascript served by the Elda server. Because
    the webapp root isn't fixed, the stylesheet reads
    location information from LDA variables that are
    set as part of creating an Elda webapp.
</p>

<ul>
    <li>_resourceRoot: the location from which the
    resources will be served, relative to the server
    root. May include a domain:port if the resources
    are on a different server.
    </li>

    <li>activeImageBase: the location within the
    resource root where the active (enabled) images
    used by the stylesheet are fetched from.
    </li>

    <li>inactiveImageBase: the location within the
    resource root where the inactive (disabled) images
    used by the stylesheet are fetched from.
    </li>

</ul>

<h3>Variables used by the Elda code</h3>

<ul>
    <li>_strip_has: (OBSOLESCENT) If this variable is defined
    and has the value "yes", the XML renderer will rename
    properties "hasWhatever" (ie where the fourth character
    is upper-case) to "whatever". This is for compatability
    with Puelia when using a Puelia-specific stylesheet.
    </li>

    <li>_suppress_media_type: If there is no .formatter
    suffix in the request URL, and no _format= query
    parameter, then the prescribed LDA behaviour is to
    see if the request headers specify an appropriate
    media type. If the requesting entity is a browser
    it almost always will (with */*), which is inconvenient
    when testing for the default default behaviour of
    sending JSON. Setting this variable to "yes" will
    cause Elda to ignore the supplied media type.
    </li>

    <li>_exceptionIfEmpty: by default, if a query for
    an item template returns no item (because the requested
    item has none of the required properties) Elda will
    generate a 404 response rather than displaying an
    empty item endpoint page. If the variable _exceptionIfEmpty
    does not have the value "<code>yes</code>", then the
    empty page is displayed.  
    </li>
</ul>

<h2><a name="wildcard-properties"></a>wildcard '*' in view property chains</h2>

<p>
    A property chain appearing in a view specification
    may contain the special element '*', meaning "any
    property". In the generated query it is replaced by
    a fresh variable. There can be any number of *-elements,
    anywhere within the chain.
</p>

<h2><a name="api-base"></a>api:base</h2>

<p>
    An LDA configuration may specify an api:base property.
    This should, if possible, be used to specify where 
    the Elda webapp is served from. If specified, all
    Elda's constructed URIs (such as those for different
    views or formats of the displayed page) will use
    that base URI with the path and query parameters
    supplied in the request. This means that a server
    at location A can generate URIs as though it were
    at location B (from which it may have been redirected).
</p>

<h2><a name="uri-rewriting">URI rewriting</a></h2>

<p>
	(<i>This feature is experimental and its details
	may change.</i>)
</p>

<p>
	An Elda configuration may have rewrite rules associated
	with it. These rules are applied to the viewed resources
	before the model is supplied by the renderer. The intention
	is that during configuration development for applications
	where the SPARQL data contains URIs that correspond to
	application pages, the "official" URIs present in the
	data will be rewritten to "local" URIs which, when
	they are used as the target of an HTTP GET, will retrieve
	local data.
</p>

<p>
	All the URIs in the view model are rewritten, including 
	the datatypes of typed literals. Lexical forms, language
	codes, and blank node IDs are not rewritten.
</p>

<p>
	The rewrite rules are specified by <code>elda:rewriteResultURIs</code>
	properties of the LDA config and apply to all (and only) endpoints
	of that config. There can be arbitrarily many such properties.
	The value(s) of the properties are resources (typically blank
	nodes) with the properties <code>elda:ifStarts</code> and
	<code>elda:replaceStartBy</code>, for example:
</p>

<pre>
... ; elda:rewriteResultURIs
	[ elda:ifStarts "http://education.data.gov.uk/"
	; elda:replaceStartBy "http://localhost:8080/elda/"
	]
</pre>

<p>
	URIs starting with the value of the <code>ifStarts</code>
	property are rewritten by replacing the <code>ifStarts</code>
	value with the <code>replaceStartBy</code> value, so
	given the rewrite rule above,
</p>

<pre>
http://education.data.gov.uk/doc/school
</pre>

<p>
	will be rewritten to
</p>

<pre>
http://localhost:8080/elda/doc/school
</pre>

<p>
	If multiple <code>ifStarts</code> values match, the
	longest is preferred. It is an error for multiple
	rules to share an <code>ifStarts</code> value.
</p>

<h2><a name="describe-all-label"></a>elda:describeAllLabel</h2>

<p>
    If a new viewer is declared with the property
    <code>elda:describeAllLabel</code>, it becomes a
    variant of the <code>describeAllViewer</code>
    where the label property used is the object of
    that property rather than <code>rdfs:label</code>.
</p>

<h2><a name="allow-reserved"></a>elda:allowedReserved</h2>

<p>
    Normally (and as prescribed by the spec) Elda will
    generate a 400 status for queries that try and use
    unknown reserved parameter names (those beginning
    with _), eg <code>?_example=17</code>.
</p>

<p>
    The property <code>elda:allowReserved</code> may be
    attached to an API or to an endpoint. Its values
    are the names of reserved parameters that should be
    ignored rather than generating status 400.
</p>

<p>
    Attachments to the API apply to all endpoints; attachments
	to one endpoint affect only that endpoint. Elda automatically
	makes the parameter name "_" allowed, since it is often used
	in JASONP queries.
</p>

<h2><a name="etags"></a>etag generation</h2>

<p>
    If an endpoint has the property <code>elda:enableETags</code>
    with value <code>true</code>, or it does not have that
    property but its parent API spec does with value 
    <code>true</code>, then Elda will generate an etag
    on successful responses. The value of the etag is derived
    from hashes of:
</p>

<ul>
    <li>the request URI</li>
    <li>the Accept header (if present)</li>
    <li>the Accept-Encoding header (if present)</li>
    <li>the response's media type</li>
    <li>the content of the model</li>
</ul>

<h2><a name="item-template-fallback"></a>item template fallback</h2>

<p>
    If an inbound URI does not match any of the uriTemplates
    of the endpoints, Elda attempts to match that URI against
    any item templates of the endpoints. If it finds a match,
    then the query is redirected to that item endpoint.
</p>

<p>
    This behaviour is currently not configurable.
</p>


<h2><a name="sparql-1.1-features"></a>SPARQL 1.1 features</h2>

<p>
    Some generated queries -- those that have view defined by
    property chains and are applied to many selected items -- 
    are rather large (exceeding a megabyte). These queries are
    repetitions of the view property accesses specialised by
    the selected item. If the SPARQL server supports nested
    selects (part of, but not limited to, SPARQL 1.1), then
    these repetitions can be replaced by a single application
    of the view wrapped round a nested select that fetches
    the items.
</p>

<p>
    Elda automatically uses nested selects if the data source 
    is a <b>local:</b> or <b>tdb:</b> model, or it the
    <code>sparqEndpoint</code> value of the API is a
    resource with an <b>extras:supportsNestedSelects</b>
    value of true, "true", or "yes". (We anticipate that
    later versions of Elda will dynamically check the server
    to see if nested selects work.)
</p>

<h2><a name="describe-thresholds"></a>DESCRIBE thresholds</h2>

<p>
    Support for nested selects applies to DESCRIBE queries as well,
    which may consist of a great many URIs when the selection
    phase generates many items. To give greater control over 
    the use of nested selects for DESCRIBE, a view may be defined 
    with the property <code>extras:describeThreshold</code>. This
    makes that view a DESCRIBE view on which nested selects
    (if available) are then only used if the number of selected 
    items exceeds the value of this property.
</p>

<p>
    The default default threshold value is 10. However, it can be
    changed. Setting the <code>extras:describeThreshold</code>
    property on an <i>endpoint</i> makes all the (describe) viewers 
    created for that endpoint have that value for their threshold.
    Setting that property on an <code>api:API</code> makes the
    default for all its endpoints be that value. 
</p>

<p>
    (Values and defaulting rules may change in later releases
    of Elda according to reported experience.)
</p>

<h2><a name="configuration-rendering"></a>configuration rendering</h2>

<p>
    Elda provides the api:base-relative URI path <code>/api-config</code>.
    Browsing this URI delivers a rendering of the various APIs that
    the Elda instance provides. Each API description shows the
    different endpoints, with their variable bindings and named views,
    and the dictionary of shortnames appropriate to this endpoint.
    By default the descriptions are hidden (for compactness) and
    are revealed by clicking on the section titles.
</p>

<p>
    The api:base-relative URI path 
    <code>/meta/<span style='color: blue'>some/uri/template</span></code>
    provides the same configuration description as <code>/api-config</code>,
    but the API and endpoint for 
    <span style='color: blue'>some/uri/template</span>
    are already opened.
</p>

<h2><a name="text-search"></a>Free-text searching</h2>

<p>
Elda allows free text from the reserved query parameter 
<code>_search</code> to be passed to the SPARQL endpoint
using the text search property <code>http://jena.apache.org/text#query</code>,
implemented by recent Jena Fuseki artifacts as an abstraction 
layer over the existing Apache Lucene and Apache Solr free-text APIs.
</p>

<p>
By default the text search is over values of <code>rdfs:label</code>,
but this can be changed by setting the <code>elda:textContentProperty</code>
of the SPARQL endpoint to the desired property in the configuration file.
</p>

<p>
This feature is experimental and details may change.
</p>

<h2><a name="formatting-extensions"><a/>Formatting extensions</h2>

<p>
If the object of an <code>api:stylesheet</code> directive starts
with the prefix "xsl:", then the stylesheet is loaded from Elda's
stylesheet directory, wherever that is. (By default it is 
<code>webapp/xsltsheets</code>, but this will become configurable.)
</p>

<p>
If a formatter has the property 
<code>http://www.epimorphics.com/vocabularies/lda#className</code>,
then the (String) object of that property must be the name of a Java
class that implements the <code>RendererFactory</code> interface.
When rendering is required, an instance of that class is invoked
to deliver a Renderer, and that Renderer is used to render the
result set.
</p>

<h3><a name="atom-feed"></a>The atom renderer</h3>

<p>
Elda contains an experimental atom-feed renderer. To use it, add
a new formatter to the configuration file:
</p>

<pre>
...
; api:formatter
    [a elda:FeedFormatter
    ; api:name "atom"
    ; elda:className "com.epimorphics.lda.renderers.FeedRendererFactory"
    ; api:mimeType "application/atom+xml"
    ; elda:feedTitle "an example Elda feed"
    ]
</pre>

<p>
The ID of the feed is the URI used to create it. The entries of the
feed correspond to the selected items of the query; the ID of an 
entry is the URI of the corresponding item.
</p>

<p>
The title of the feed is set using the elda:feedTitle
property of the formatter in the LDA config, as in the example above.
The title of an entry is set from the value of the first of the
properties in the list 

</p>
<pre>
<code>api:label</code>
<code>skos:prefLabel</code>
<code>rdfs:label</code> 
</pre>
<p>

that is defined; this list can be changed
by setting the value of the formatter's <code>elda:feedLabelProperties</code> property.
</p>

<p>
The update time of a feed is the latest of the updated
times of its entries.
</p>

<p>
The update time of an entry is the value of the first
property in the list:
</p>

<pre>
dct:modified
dct:date
dct:dateAccepted
dct:dateSubmitted
dct:created
</pre>

<p>
that is defined. This list can be changed by setting the value of the
formatter's <code>elda:feedFateProperties</code> property.
</p>

<p>
The content of an entry is similar to the XML rendering of the
resource for this entry. Currently <b>circularity checking is not
available</b>. The entry is given its own namespace, which defaults
to the Elda namespace but can be set in the feed configuration using
the property <code>elda:feedNamespace</code>.
</p>

<h2><a name="statistics"></a>statistics</h2>

<p>
    The api:base-relative URI path <code>/control/show-stats</code> displays
    statistics about the queries that this Elda instance has handled, including:
</p>

<ul>
    <li>the total number of requests made</li>
    <li>the number of requests that failed</li>
    <li>the number of selection cache hits</li>
    <li>the number of view cache hits</li>
</ul>

<p>
    (Elda maintains two internal caches, one mapping the computed selection
    query to the list of items it generates, the other mapping (list of
    item, view) pairs to generated result sets. These are independant of
    any caches provided by <i>eg</i> an Apache server wrapping Elda.)
</p>

<ul>
    <li>the elapsed time dealing with all requests</li>
    <li>the elapsed time taken for item-selection queries</li>
    <li>the elapsed time taken for view-display queries</li>
    <li>the elapsed time taken to render an Elda result</li>
    <li>any remaining non-query non-rendering time</li>
</ul>

<p>
    All of these results show the total time, the mean time over all
    requests, and the maximum and minimum times over all requests.
</p>

<ul>
    <li>the size of the rendered results</li>
    <li>the size of the select queries</li>
    <li>the size of the view queries</li>
</ul>

<p>
    All of these results show the total size (in [kilo-]bytes),
    and the mean, maximum, and minimum over all requests.
</p>

<p>
    The display also breaks down rendering sizes and times by
    the rendering format (ie JSON/XML/HTML ...).
</p>

<h3>JMX statistics</h3>

<p>
Elda can also serve limited JMX statistics (the same ones as are
accessible using <code>show-stats</code>) by enabling the appropriate 
listeners in web.xml:

<pre>
&lt;listener>
  &lt;listener-class>com.epimorphics.lda.jmx.Statistics&lt;/listener-class>
  &lt;listener-class>com.epimorphics.lda.jmx.CacheControl&lt;/listener-class>
&lt;/listener>
</pre>

This feature is experimental; it may be dropped in a future release.

</p>

<h2><a name="cache"></a>Cache</h2>

<p>
Elda caches the results of queries so that they may be re-served
quickly. When the cache gets "too full", it is reset. "Too full"
by default is measured by the number of triples in the cache;
the default limit is 20000 triples.
</p>

<p>
The cache policy can be changed by setting the property
<code>elda:cachePolicyName</code> to a string of the
form <code>"name:integer"</code> where <code>name</code>
is the name of a policy, eg <b>default</b>, and the optional
<code>:integer</code> gives an associated limit. 
</p>

<p>
The available cache policies are 
<ul>
	<li><code>default</code> &mdash; same as limit-triples.</li>
	
	<li><code>limit-triples</code> &mdash; clear the cache when
		the number of triples retained is greater than the limit.
	</li> 
	
	<li><code>limit-entries</code> &mdash; clear the cache when
		the number of entries is greater than the limit.
	</li>
	
	<li><code>perma-cache</code> &mdash; keep everything
		(not a good choice in production).
	</li>
</ul>
</p>

<p>
	Cache policies can be attached to the API spec and over-ridden
	on individual endpoints.
</p>

<h2><a name="using-elda-from-java"></a>Using Elda directly</h2>

<p>You don't need to go through a servlet (or restlet)
framework to exploit Elda. You can call the components
yourself and supply whatever glue you like. Note however
that details of the code structure may change between releases.
</p>

<h3>Creating an APISpec</h3>

<p>
The constructor
<pre>
APISpec(FileManager fm, Resource config, ModelLoader forVocab)
</pre>

delivers a new APISpec object configured from the given
Resource. You may have chosen a Resource with a known 
URI in a config model, or found one with <code>rdf:type</code>
<code>api:API</code>, depending on your usecase. The
<code>ModelLoader</code> is only used if the config has
<code>api:vocabulary</code> elements, in which case it
loads the models for its API vocabulary. The <code>FileManager</code>
is used for accessing data sources.
</p>

<p>
Given an APISpec, the method <code>getEndpoints()</code>
delivers a list of <code>APIEndpoint</code> objects corresponding
(in no defined order) with the endpoint descriptions in the
config model. 
</p>

<h3>Running an endpoint</h3>

<p>
You can then invoke
<pre>
APIEndpointUtil.call(APIEndpoint.Request r, Match match, String contextPath, MultiMap<String, String> queryParams)
</pre>
where
</p>

<ul>
  <li><i>r</i> is a Request object describing this LDA request. A
	Request itself contains:
	  <ul>
		<li>a Controls object for timing information</li>
		<li>the request URI</li>
		<li>bindings of LDA variables to values</li>
		<li>the shortname creation mode</li>
		<li>the name of the rendering format</li>
	  </ul>
  </li>

  <li><i>Match match</i> wraps the endpoint object and the variable bindings that
    made when matching the endpoint's <code>api:uriTemplate</code> against the
    request URI. The usual way to get a Match object is to call <code>getMatch</code>
    on a suitable <code>Router</code> value.
  </li>

  <li><i>URI requestURI</i> is the request URI for this request.
  </li>

  <li><i>contextPath</i> is the context path to assume (it is written into the
	variable bindings)
  </li>

  <li><i>MultiMap queryParams</i> is a map from query parameter names to their
    (string) values.
  </li>

</ul>

<p>
The call returns a three-element object which contains the
<code>ResultSet</code> of the query execution (the result
model and selected items), a map (the <i>term bindings</i>
from shortnames to their URIs as appropriate for this resultset, 
and the (updated) variable Bindings.
</p>

<h3>Rendering results</h3>

<p>
Once you have chosen a renderer <code>R</code> to use for the 
result set, the invocation

<pre>
R.render( t, rc, termBindings, results )
</pre>

where <code>t</code> is a <code>Times</code> object,
delivers a String which is the rendering of <code>results</code>
according to the RenderContext <code>rc</code>, which you can
construct from the <code>VarValues</code> embedded in the call
context, the context path, and an AsURL object to convert URI
fragments into full URIs. The termBindings should be the
map returned from <code>APIEndpointUtil.call</code>.
</p>

<p>
The method call <code>R.getMediaType()</code> returns the media
type for the renderer's result. 
</p>


<h2><a name="building-elda"></a>Building Elda</h2>

<p>
  Prerequisites: 
  <a href="http://java.com/">Java</a> (underlying platform),
  <a href="http://mercurial.selenic.com/">Mercurial</a> (to fetch the sources),
  <a href="http://maven.apache.org/Maven">Maven</a> (build management).
  Maven will download remaining necessary jars for Jena, Jersey, etc.
</p>

<p>
  Download the Elda sources:

<pre>
hg clone https://elda.googlecode.com/hg/ elda  
</pre>

places the Elda sources in ./elda (which is created if necessary).
</p>

<p>
Running
<pre>
mvn clean install
</pre>
will now build the Elda jars and put them into your local
Maven repository, along with all the jars that they depend
on. You can then either use Maven to build your own
application with those jars as dependencies, or extract
them and embed them in your own libraries.
</p>

<p>
Look in the (automatically created) file
<code>/lda/src/main/java/com/epimorphics/lda/Version.java</code>
to see which version of Elda is being built. If you want to use
a non-SNAPSHOT version, use 

<pre>
hg update -r REVISION
</pre>

before running maven, where REVISION is your choice of the revision
tags you get from running:

<pre>
hg tags
</pre>

and selecting a tag that looks like <code>elda-1.X.Y</code>;
that is the shape of tag generated by the Elda release process.
</p>

<p>
As of Elda 1.2.23, the names of Elda modules (and the names of
the corresponding directories in the Elda sources) have changed.
</p>


<h1><a name="accepted-content-types"></a>Accepted content types</h1>

<p>
Elda accepts the following content types by default.
</p>

<ul>
    <li>text/javascript, application/javascript:
        for JSONP on some browsers.
    </li>
    <li>text/plain:
        Plain text JSON.
    </li>
    <li>application/rdf+xml, text/turtle:
        RDF/XML or Turtle representations of models.
    </li>
    <li>application/json: model rendered as JSON.
    </li>
    <li>text/xml, application/xml:
		model rendered as XML with whichever content type was
		asked for. (The renderings are identical.)
    </li>
    <li>text/html:
        model rendered by stylesheet applied to XML rendering.
    </li>
</ul>


<div class="footer">
<hr>
&copy; Copyright 2011 Epimorphics Limited. For licencing conditions see
<a href="http://elda.googlecode.com/hg/LICENCE.html">http://elda.googlecode.com/hg/LICENCE.html</a>.
</div>
</div>

</body>
</html>

